<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Program Annotations Affecting the Decompiler</title>
<link rel="stylesheet" type="text/css" href="help/shared/DefaultStyle.css">
<link rel="stylesheet" type="text/css" href="../../shared/languages.css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="Decompiler.html" title="Decompiler">
<link rel="up" href="Decompiler.html" title="Decompiler">
<link rel="prev" href="DecompilerConcepts.html" title="Decompiler Concepts">
<link rel="next" href="DecompilerOptions.html" title="Decompiler Options">
</head>
<body><div class="chapter">
<div class="titlepage"><div><div><h1 class="title">
<a name="DecompilerAnnotations"></a>Program Annotations Affecting the Decompiler</h1></div></div></div>
  

<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="AnnoteFunctionBody"></a>Machine Instructions</h2></div></div></div>
  
  <p>
    Individual <span class="bold"><strong>machine instructions</strong></span>
    make up the biggest source of information when the
    Decompiler analyzes a function.  Instructions are translated from their
    processor-specific form into Ghidra's IR language (see <a class="xref" href="DecompilerConcepts.html#ConceptPcode" title="P-code">P-code</a>),
    which provides both the control-flow behavior of the instruction and the detailed
    semantics describing how the processor and memory state are affected. The translation is controlled by
    the underlying processor model and, except in limited circumstances, cannot be directly altered
    from the tool. Flow Overrides (see below) can change how certain control flow is translated
    and, depending on the processor, how context registers affect p-code (see <a class="xref" href="DecompilerAnnotations.html#AnnoteContextRegister" title="Context Registers">Context Registers</a>).
  </p>
  <p>
    Outside of the tool, users <span class="emphasis"><em>can</em></span> modify the model specification itself.
    See the document "SLEIGH: A Language for Rapid Processor Specification."
  </p>
  <p>
    Decompiling a function starts by analyzing the control flow of machine instructions.
    Control flow is traced from the first instruction, through additional instructions depending
    on their flow semantics (see <a class="xref" href="DecompilerConcepts.html#ConceptControlFlow" title="P-code Control Flow">P-code Control Flow</a>).  All paths are traced through instructions with
    any form of <span class="emphasis"><em>fall-through</em></span> or <span class="emphasis"><em>jump</em></span>
    semantics until an instruction with <span class="emphasis"><em>terminator</em></span> semantics is
    reached, which is usually a formal <span class="emphasis"><em>return</em></span> (return from subroutine) instruction.
    Flow is not traced into called functions, in this situation.  Instructions
    with <span class="emphasis"><em>call</em></span> semantics are treated only as if they fall through.
  </p>
  <p>
    An <span class="bold"><strong>entry point</strong></span> is the address of the instruction first
    executed when the function is called.
  </p>
  <p>
    A <span class="bold"><strong>function body</strong></span> is the set of addresses reached by control-flow
    analysis and the machine instructions at those addresses.
  </p>
  <div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="AnnoteEntryPoint"></a>Entry Point</h3></div></div></div>
    
    <p>
      The <span class="emphasis"><em>entry point</em></span> address for a function plays a pivotal role for
      analysis using the Decompiler. Ghidra generally associates
      a formal <span class="emphasis"><em>Function Symbol</em></span> and an underlying
      <span class="emphasis"><em>Function</em></span> object at this address, which are the key elements that
      need to be present to trigger decompilation
      (see <a class="ulink" href="help/topics/FunctionPlugin/Functions.htm" target="_top">Functions</a>).
      The Function object stores the function body, parameters, local variables, and
      other information critical to the decompilation process.
    </p>
    <p>
      Function Symbols and Function objects are generally created automatically by a Ghidra
      analyzer when initially importing a binary executable and running Auto Analysis.
      If necessary, however, a user can manually create a Function object from a Listing window
      by using the <span class="emphasis"><em>Create Function</em></span> command (pressing the 'F' key), when the cursor
      is placed on the function's entry point
      (see <a class="ulink" href="help/topics/FunctionPlugin/Functions.htm#Create_Function" target="_top">Create Function</a>).
    </p>
  </div>
  <div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="AnnoteFormalFunctionBody"></a>Formal Function Body</h3></div></div></div>
    
    <p>
      When a function is created, Ghidra stores its function body as a set of addresses in the
      Program database. This <span class="emphasis"><em>formal</em></span> function body delineates the function
      from all the other kinds of data within the Program and lets Ghidra immediately link addresses
      in the middle of the function to the entry point and the Function object.  Decompiler windows
      in particular use the formal function body to know which function to decompile in response
      to a navigation event to an arbitrary address.
    </p>
    <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="help/shared/warning.png"></td>
<th align="left"></th>
</tr>
<tr><td align="left" valign="top">
      The Decompiler does <span class="emphasis"><em>not</em></span> use the formal function body when it computes
      control flow; it recomputes its own idea of the function body starting from the entry point
      it is handed.  If the formal function body was created manually, using a selection for instance,
      or in other extreme circumstances, the Decompiler's view of the function body may not match
      the formal view. This can lead to confusing behavior, where clicking in a Decompiler window
      may unexpectedly navigate the window away from the function.
    </td></tr>
</table></div>
  </div>

  <div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="AnnoteFlowOverride"></a>Flow Overrides</h3></div></div></div>
    
    <p>
      Control-flow behavior for a machine instruction is generally determined by its underlying
      p-code (see <a class="xref" href="DecompilerConcepts.html#ConceptControlFlow" title="P-code Control Flow">P-code Control Flow</a>), but this can be changed by applying a Flow Override.
      A <span class="bold"><strong>Flow Override</strong></span> maintains the overall semantics of a branching instruction
      but changes how the branch is interpreted.  For instance, a <code class="code">JMP</code> instruction, which traditionally
      represents a branch within a single function, can be overridden to represent a call to a new function.
      Flow Overrides are applied by Analyzers or manually by the user.
    </p>
    <p>
      The Decompiler automatically incorporates any relevant Flow Overrides into its
      analysis of a function. This can have a significant impact on results. The
      types of possible Flow Overrides include:
      </p>
<div class="informalexample">
      <div class="variablelist"><dl class="variablelist">
<dt><span class="term"><span class="bold"><strong>BRANCH Override</strong></span></span></dt>
<dd>
	  <p>
	    Treats the primary <span class="emphasis"><em>CALL</em></span> or <span class="emphasis"><em>RETURN</em></span>
	    behavior of the instruction as if it were a <span class="emphasis"><em>BRANCH</em></span>
	    within the function.  For <span class="emphasis"><em>CALL</em></span> instructions,
	    the call target becomes the branch destination,
	    and the instruction is no longer assumed
	    to fall through. <span class="emphasis"><em>RETURN</em></span> instructions become an
	    indirect branch, and the Decompiler will attempt to recover branch
	    destinations using <span class="emphasis"><em>switch</em></span> analysis.
	  </p>
	</dd>
<dt><span class="term"><span class="bold"><strong>CALL Override</strong></span></span></dt>
<dd>
	  <p>
	    Treats the primary <span class="emphasis"><em>BRANCH</em></span> or <span class="emphasis"><em>RETURN</em></span>
	    behavior of the instruction as if it were a <span class="emphasis"><em>CALL</em></span>.
	    A <span class="emphasis"><em>BRANCH</em></span> becomes a fall through instruction, and the destination address becomes
	    the call target, which may no longer be considered part of the function.  The computed
	    address for an indirect <span class="emphasis"><em>BRANCH</em></span> or <span class="emphasis"><em>RETURN</em></span> instruction becomes
	    the target address of an indirect <span class="emphasis"><em>CALL</em></span>.
	  </p>
	</dd>
<dt><span class="term"><span class="bold"><strong>CALL_RETURN Override</strong></span></span></dt>
<dd>
	  <p>
	    Treats the primary <span class="emphasis"><em>BRANCH</em></span> or <span class="emphasis"><em>RETURN</em></span>
	    behavior of the instruction as if it executed a <span class="emphasis"><em>CALL</em></span> followed
	    by a <span class="emphasis"><em>RETURN</em></span> operation.
	    The destination address of a <span class="emphasis"><em>BRANCH</em></span> becomes the call target,
	    which may no longer be considered part of the function.  The computed address for
	    an indirect <span class="emphasis"><em>BRANCH</em></span> or <span class="emphasis"><em>RETURN</em></span> instruction becomes
	    the target address of an indirect <span class="emphasis"><em>CALL</em></span>.
	  </p>
	</dd>
<dt><span class="term"><span class="bold"><strong>RETURN Override</strong></span></span></dt>
<dd>
	  <p>
	    Treats an indirect <span class="emphasis"><em>BRANCH</em></span> or <span class="emphasis"><em>CALL</em></span>
	    instruction as if it were a <span class="emphasis"><em>RETURN</em></span> instruction, terminating
	    the control-flow path within the function. The computed destination address is
	    considered part of the return mechanism of the function and may no longer be
	    explicitly displayed in the output.
	    An indirect <span class="emphasis"><em>BRANCH</em></span> no longer invokes switch analysis during
	    decompilation.
	  </p>
	</dd>
</dl></div>
      </div>
<p>
    </p>
  </div>
</div>

<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="AnnoteComments"></a>Comments</h2></div></div></div>
  
  <p>
    The Decompiler automatically incorporates comments from the Program database into its
    output.  Comments in Ghidra are centralized and can be created and displayed by multiple
    Program views, including the Decompiler.  Comments created from a Decompiler window will
    show up in a Listing window for instance, and vice versa.
  </p>
  <p>
    For the purposes of understanding comments within the Decompiler, keep in mind that:
    </p>
<div class="informalexample">
      <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: bullet; ">
<li class="listitem" style="list-style-type: disc">
	  An individual comment is associated with a specific <span class="emphasis"><em>address</em></span> in the Program.
	</li>
<li class="listitem" style="list-style-type: disc">
	  There are 5 different types of comments:
	  <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; ">
<li class="listitem" style="list-style-type: circle">
	      <span class="emphasis"><em>Plate</em></span>
	    </li>
<li class="listitem" style="list-style-type: circle">
	      <span class="emphasis"><em>Pre</em></span>
	    </li>
<li class="listitem" style="list-style-type: circle">
	      <span class="emphasis"><em>Post</em></span>
	    </li>
<li class="listitem" style="list-style-type: circle">
	      <span class="emphasis"><em>End-of-line (EOL)</em></span>
	    </li>
<li class="listitem" style="list-style-type: circle">
	      <span class="emphasis"><em>Repeatable</em></span>
	    </li>
</ul></div>
	</li>
</ul></div>
    </div>
<p>
  </p>
  <p>
    For general documentation on creating and editing comments within Ghidra, see
    <a class="ulink" href="help/topics/CommentsPlugin/Comments.htm" target="_top">Comments</a>.
  </p>

  <div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="CommentDisplay"></a>Display</h3></div></div></div>
    
  <p>
    The Decompiler collects and displays comments associated with any address in the
    formal <span class="emphasis"><em>function body</em></span> currently decompiling.
    The comments are integrated line by line into the decompiled code, and an
    individual comment is displayed on the line <span class="emphasis"><em>before</em></span> the
    line of code incorporating the instruction associated with the comment's
    address.
  </p>
  <p>
    Because a single line of code typically encompasses multiple machine instructions,
    there is a possibility that multiple comments at different addresses apply to
    the same line.  In this case, the Decompiler displays each comment on its
    own line, in address order, directly before the line of code.
  </p>
  <p>
    Because the output of the Decompiler can be a heavily transformed version compared
    to the original machine instructions, it is possible that individual instructions
    no longer have explicit tokens representing them in the output.  Comments attached
    to these instruction will still be displayed in the Decompiler output with the
    closest associated line of code, usually within the same basic block.
  </p>
  <p>
    By default, the Decompiler displays only the <span class="emphasis"><em>Pre</em></span> comments
    within the body of the function.  It also displays <span class="emphasis"><em>Plate</em></span>
    comments, but only if they are attached to the <span class="emphasis"><em>entry point</em></span>
    of the function. In this case, they are displayed first in the Decompiler output,
    along with WARNING comments, before the function declaration.  Other comment
    types can be configured to be part of Decompiler output by changing the
    Decompiler display options (see <a class="xref" href="DecompilerOptions.html#CommentOptions"><span class="bold"><strong>Display &lt;kind-of&gt; Comments</strong></span></a>).
  </p>
  <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="help/shared/warning.png"></td>
<th align="left"></th>
</tr>
<tr><td align="left" valign="top">
    Unlike a Listing window, the Decompiler does not alter how a comment is
    displayed based on its type.
    All enabled types of comment are displayed in the same way, on
    a separate line before the line of code associated with the address.
  </td></tr>
</table></div>
  </div>

  <div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="CommentUnreachable"></a>Unreachable Blocks</h3></div></div></div>
    
    <p>
      The Decompiler may decide as part of its analysis that individual
      <span class="emphasis"><em>basic blocks</em></span> are unreachable and not display them in the output.
      In this case, any comments associated with addresses in the unreachable block
      will also not be displayed.
    </p>
  </div>

  <div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="CommentWarnings"></a>Warning Comments</h3></div></div></div>
    
    <p>
      The Decompiler can generate internal warnings during its analysis and will incorporate
      them into the output as comments in the same way as the user-defined
      comments described above. They are not part of Ghidra's comment system, however, and
      cannot be edited.  They can be distinguished from normal comments by the word
      'WARNING' at the beginning of the comment.
      </p>
<div class="informalexample">
	<code class="code">/* WARNING: ... */</code>
      </div>
<p>
    </p>
  </div>
</div>

<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="AnnoteVariables"></a>Variable Annotations</h2></div></div></div>
  
  <p>
    Variable annotations are the most important way to get names and data-types
    that are meaningful to the user incorporated into the Decompiler's output.
    A <span class="bold"><strong>variable</strong></span> in this context is loosely defined
    as any piece of memory that code in the Program treats as a logical entity.
    The Decompiler works to incorporate all forms of annotation into its output
    for any variable pertinent to the function being analyzed.
  </p>
  <p>
    At a minimum, a variable annotation in Ghidra provides a:
    </p>
<div class="informalexample">
      <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: bullet; ">
<li class="listitem" style="list-style-type: disc">
	  <span class="bold"><strong>Symbol name</strong></span>,
	</li>
<li class="listitem" style="list-style-type: disc">
	  <span class="bold"><strong>Data-type</strong></span>, and
	</li>
<li class="listitem" style="list-style-type: disc">
	  <span class="bold"><strong>Storage location</strong></span>.
	</li>
</ul></div>
    </div>
<p>
  </p>
  
  <div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="VariableCreate"></a>Creating Variable Annotations</h3></div></div></div>
    
  <p>
    Ghidra provides various ways that a name and other attributes can be ascribed
    to a variable.  These break up roughly into <span class="emphasis"><em>global</em></span> variables,
    defined directly on memory in the Program image, and variables that are
    <span class="emphasis"><em>local</em></span> to a function.
  </p>
  <p>
    Global variable annotations are created from the tool by applying a data-type to a memory
    location in a Listing window, either by invoking a command from the <span class="emphasis"><em>Data</em></span>
    pop-up menu or by dragging a data-type from the <span class="emphasis"><em>Data Type Manager</em></span>
    window directly onto the memory location.  Refer to the documentation:
    </p>
<div class="informalexample">
      <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: none; "><li class="listitem" style="list-style-type: none">
	  <a class="ulink" href="help/topics/DataPlugin/Data.htm#ApplyDataType" target="_top">Applying Data Type</a>
	</li></ul></div>
    </div>
<p>
  </p>
  <p>
    Local variables annotations are created from the Listing using various editor dialogs. See, in particular:
    </p>
<div class="informalexample">
      <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: none; ">
<li class="listitem" style="list-style-type: none">
	  <a class="ulink" href="help/topics/FunctionPlugin/Variables.htm#Edit_Function" target="_top">Function Signature Dialog</a>
	</li>
<li class="listitem" style="list-style-type: none">
	  <a class="ulink" href="help/topics/StackEditor/StackEditor.html" target="_top">Stack Frame Editor</a>
	</li>
<li class="listitem" style="list-style-type: none">
	  <a class="ulink" href="help/topics/ReferencesPlugin/References_from.htm#Create_Default_Reference" target="_top">Creating a Default Reference</a>
	</li>
</ul></div>
    </div>
<p>
  </p>
  <p>
    The <span class="emphasis"><em>Decompiler</em></span> window also provides numerous ways of annotating variables, both local and global. In particular,
    see the commands:
    </p>
<div class="informalexample">
      <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: none; ">
<li class="listitem" style="list-style-type: none">
	  <a class="xref" href="DecompilerWindow.html#ActionRenameVariable" title="Rename Variable">Rename Variable</a>
	</li>
<li class="listitem" style="list-style-type: none">
	  <a class="xref" href="DecompilerWindow.html#ActionRetypeVariable" title="Retype Variable">Retype Variable</a>
	</li>
<li class="listitem" style="list-style-type: none">
	  <a class="xref" href="DecompilerWindow.html#ActionCommitParams" title="Commit Params/Return">Commit Params/Return</a>
	</li>
<li class="listitem" style="list-style-type: none">
	  <a class="xref" href="DecompilerWindow.html#ActionCommitLocals" title="Commit Local Names">Commit Local Names</a>
	</li>
</ul></div>
    </div>
<p>
  </p>
  </div>
  
  <div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="VariableSymbol"></a>Variable Symbols</h3></div></div></div>
    
    <p>
      Ghidra maintains its own symbol table that supports namespaces and function
      scopes, and variable names are automatically incorporated into this.
      In order to widely accommodate different use cases, Ghidra's symbol
      table has extremely lax naming rules.  Ghidra
      may allow names that conflict with the stricter rules of the language
      the Decompiler is attempting to produce. The Decompiler does not currently
      have an option that checks for this. Users should be aware of:
      </p>
<div class="informalexample">
	<div class="variablelist"><dl class="variablelist">
<dt><span class="term">Illegal Characters</span></dt>
<dd>
	    <p>
	      Ghidra symbols allow almost every printable character except
	      a space in a symbol name; punctuation and keywords can be incorporated.
	    </p>
	  </dd>
<dt><span class="term">Duplicate Symbols</span></dt>
<dd>
	    <p>
	      Ghidra allows different functions to have the same name, even within the same
	      namespace, in order to model languages that support <span class="emphasis"><em>function overloading</em></span>.
	      In most languages, such functions would be expected to have distinct prototypes to allow
	      the symbols to be distinguished in context.   Ghidra and the Decompiler, however, do not check
	      for this, as prototypes may not be known.
	    </p>
	  </dd>
</dl></div>
      </div>
<p>
    </p>
    
    <div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="SymbolScope"></a>Variable Scope</h4></div></div></div>
      
    <p>
      All variables belong to either a <span class="emphasis"><em>global</em></span> or <span class="emphasis"><em>local</em></span>
      scope, which directly affects how the variable is treated in the Decompiler's data-flow
      analysis.
      Annotations created by applying a data-type directly to a memory location in the Listing
      are automatically added to the formal <span class="emphasis"><em>global</em></span> namespace.
      Ghidra can create other custom namespaces that are considered global in this sense, and
      renaming actions provide options that let individual global annotations be moved into
      these namespaces.
      Dialogs that are brought up in the context of a function, like the Function Signature Editor,
      create variable annotations that are local to that function.
    </p>
    <p>
      A global variable annotation forces the Decompiler to treat the memory location as if its value
      persists beyond the end of the function. The variable must <span class="emphasis"><em>exist</em></span>
      at all points of the function body, generally at the same memory location.
    </p>
    <p>
      Local variables,
      in contrast, do not generally exist across the whole function, but come into scope
      at the instruction that first writes to them, and then exist only up to the last
      instruction that reads them.  The memory location storing a local variable
      at one point of the function may be reused for different variables at other points.
      This can cause ambiguity in how the Decompiler should treat a given memory location used
      for storing local variables, which the user may want to steer. See the discussion
      in <a class="xref" href="DecompilerAnnotations.html#AnnoteStorage" title="Variable Storage">Variable Storage</a>.
    </p>
    <p>
    </p>
    </div>
    
  </div>

  <div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="AnnoteDatatype"></a>Variable Data-types</h3></div></div></div>
    
    <p>
      Ghidra provides extensive support for naming and describing
      <span class="bold"><strong>data-types</strong></span> that are tailored for the Program
      being analyzed. Data-types that are explicitly part of a variable annotation
      are, to the extent possible, automatically incorporated
      into the Decompiler's analysis.
    </p>
    <div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="DecompilerDataTypes"></a>Data-types Supported by the Decompiler</h4></div></div></div>
      
      <p>
	The Decompiler understands traditional primitive data-types in all their various sizes,
	like integers, floating-point numbers, booleans, and characters. It also understands
	pointers, structures, and arrays, letting it support
	arbitrarily complicated composite data-types. Ghidra provides
	some data-types with specialized display capabilities that don't have a natural representation
	in the high-level language output by the Decompiler. The Decompiler treats these as
	black-box data-types, preserving the name, but treating the underlying data either as an integer
	or simply as an array of bytes.
      </p>

      <div class="sect4">
<div class="titlepage"><div><div><h5 class="title">
<a name="TypeUndefined"></a>Undefined</h5></div></div></div>
	
	<p>
	  The <span class="emphasis"><em>undefined</em></span> data-types are supported in their various sizes:
	  <span class="bold"><strong>undefined1</strong></span>, <span class="bold"><strong>undefined2</strong></span>,
	  <span class="bold"><strong>undefined4</strong></span>, etc.  In Ghidra, the undefined
	  data-types let the user specify the size of a variable, while formally declaring that
	  other details about the data-type are unknown.
	</p>
	<p>
	  For the Decompiler, undefined data-types, as an annotation, have the important special meaning
	  that the Decompiler should let its analysis determine the final data-type presented in the
	  output for the variable (see <a class="xref" href="DecompilerAnnotations.html#AnnoteForcing" title="Forcing Data-types">Forcing Data-types</a> below).
	</p>
      </div>
      <div class="sect4">
<div class="titlepage"><div><div><h5 class="title">
<a name="TypeVoid"></a>Void</h5></div></div></div>
	
	<p>
	  The <span class="bold"><strong>void</strong></span> data-type is supported but treated specially by
	  the Decompiler, as does Ghidra in general.  A <span class="bold"><strong>void</strong></span> can be
	  used to indicate the absence of a return value in function prototypes, but cannot be used
	  as a general annotation on variables.  A void pointer, <span class="bold"><strong>void *</strong></span>,
	  is possible; the Decompiler treats it as a pointer to an unknown data-type.
	</p>
      </div>
      <div class="sect4">
<div class="titlepage"><div><div><h5 class="title">
<a name="TypeInteger"></a>Integer</h5></div></div></div>
	
	<p>
	  Integer data-types, both signed and unsigned, are supported up to a size of 8 bytes. Larger
	  sizes are supported internally but are generally represented as an array of bytes in
	  Decompiler output.  Nonstandard integer sizes of 3, 5, 6, and 7 bytes are also supported.
	</p>
	<p>
	  The standard C data-type names: <span class="bold"><strong>int</strong></span>, <span class="bold"><strong>short</strong></span>,
	  <span class="bold"><strong>long</strong></span>, and <span class="bold"><strong>long long</strong></span> are mapped to specific sizes
	  based on the processor and compiler selected when importing the Program.
	</p>
      </div>
      <div class="sect4">
<div class="titlepage"><div><div><h5 class="title">
<a name="TypeBoolean"></a>Boolean</h5></div></div></div>
	
	<p>
	  A 1-byte boolean data-type is supported. Boolean constants are rendered as either the
	  token <span class="bold"><strong>true</strong></span> or the token <span class="bold"><strong>false</strong></span>.
	</p>
      </div>
      <div class="sect4">
<div class="titlepage"><div><div><h5 class="title">
<a name="TypeFloat"></a>Floating-point</h5></div></div></div>
	
	<p>
	  Floating-point sizes of 4, 8, 10, and 16 are supported, mapping in all cases currently to the
	  <span class="bold"><strong>float</strong></span>, <span class="bold"><strong>double</strong></span>,
	  <span class="bold"><strong>float10</strong></span>, and <span class="bold"><strong>float16</strong></span>
	  data-types, respectively.  The Decompiler currently cannot display floating-point constants
	  that are bigger than 8 bytes.
	</p>
      </div>
      <div class="sect4">
<div class="titlepage"><div><div><h5 class="title">
<a name="TypeChar"></a>Character</h5></div></div></div>
	
	<p>
	  ASCII- and Unicode-encoded character data-types are supported for sizes of 1, 2, and 4.  The size effectively
	  chooses between the UTF8, UTF16, and UTF32 character encodings, respectively. The standard
	  C data-type names <span class="bold"><strong>char</strong></span> and <span class="bold"><strong>wchar_t</strong></span> are
	  mapped to one of these sizes based on the
	  processor and compiler selected when importing the Program.
	</p>
      </div>
      <div class="sect4">
<div class="titlepage"><div><div><h5 class="title">
<a name="TypeString"></a>String</h5></div></div></div>
	
	<p>
	  Terminated strings, encoded either in ASCII or Unicode, are supported.  The Decompiler converts
	  Ghidra's dedicated string data-types like <span class="bold"><strong>string</strong></span> to
	  an array-of-characters data-type, such as <span class="bold"><strong>char[]</strong></span>,
	  where the character size matches the encoding.
	  A pointer-to-character data-type like
	  </p>
<div class="informalexample">
	    <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: none; ">
<li class="listitem" style="list-style-type: none">
		<code class="code">char *</code> or
	      </li>
<li class="listitem" style="list-style-type: none">
		<code class="code">wchar_t *</code>
	      </li>
</ul></div>
	  </div>
<p>
	  is also treated as a potential string reference. The Decompiler can infer terminated strings if this
	  kind of data-type propagates to constant values during its analysis.
	</p>
	<p>
	  Strings should be fully rendered in Decompiler output,
	  with non-printable characters escaped using either traditional sequences like '\r', '\n' or using Unicode
	  escape sequences like '\xFF'.
	</p>
      </div>
      <div class="sect4">
<div class="titlepage"><div><div><h5 class="title">
<a name="TypePointer"></a>Pointer</h5></div></div></div>
	
	<p>
	  Pointer data-types are fully supported.  A pointer to any other supported data-type is
	  possible.  The data-type being pointed to, whether it is a primitive, structure, or another pointer,
	  informs how the Decompiler renders a dereferenced pointer or other pointer expression.
	</p>
        <p>
	  The Decompiler automatically assumes that a pointer may reference an array of the underlying data-type.
	  If an integer value is added to the pointer and the value is known to be a multiple of the data-type's size,
	  the expression is treated as either <span class="emphasis"><em>pointer arithmetic</em></span> or as an array access, and the multiplication
	  factor is hidden. Adding smaller integers to a structure pointer typically results in a
	  <span class="emphasis"><em>field access</em></span> expression using the '-&gt;' or other language specific token. See the discussion
	  on <span class="emphasis"><em>Structures</em></span> below.
	</p>
	<p>
	  The default pointer size is set based on the processor and compiler selected when the Program is
	  imported and generally matches the size of the <span class="bold"><strong>ram</strong></span> or equivalent
	  address space. Different pointer sizes within the same Program are possible. The Decompiler generally
	  expects the pointer size to match the size of the address space being pointed to, but individual
	  architectures can model different size pointers into the space (such as <span class="emphasis"><em>near</em></span> pointers).
	</p>
	<p>
	  For processors with more than one memory address space, pointer data-types do not by default indicate
	  a preferred address space and can be used to reference data in any address space.
	  Where there is ambiguity, the Decompiler attempts to determine the correct address space from the context
	  of its use within the function.  It is possible to create pointer data-types with an
	  explicitly preferred address space, see <a class="xref" href="DecompilerAnnotations.html#AttributeAddressPointer" title="Address Space Pointers">Address Space Pointers</a>.
	</p>
      </div>
      <div class="sect4">
<div class="titlepage"><div><div><h5 class="title">
<a name="TypeArray"></a>Array</h5></div></div></div>
	
	<p>
	  Array data-types are fully supported. The array element can be any other supported data-type
	  with a fixed size.
	</p>
	<p>
	  For code that accesses arrays, the Decompiler keeps track of the array index and automatically
	  hides the underlying multiplication needed to account for the size of an element.  The access is
	  displayed as an expression using standard square brace notation, '[' and ']'.
	  For an access that covers more than one array element simultaneously, the Decompiler will either
	  generate a pointer expression that casts to a data-type of the correct size or may generate a
	  special token representing the accessed portion of the array.
          </p>
<div class="informalexample">
	    <pre class="programlisting">
	      text[iVar1] = 'a';           // Assigning a character to a variable index of the array
	      cVar2 = text[7];             // Reading a fixed element from an array
	      text._8_2_ = 0x7677;         // Auto-generated token indicating multiple elements are assigned at once
	    </pre>
          </div>
<p>
	  For an auto-generated token like <code class="code">_8_2_</code>, the first integer indicates the offset in bytes
	  of the access from the start of the array, and the second integer indicates the number of bytes being accessed.
	</p>
	<p>
	  If more then one element is being accessed simultaneously, the Decompiler may try to split
	  the access into logical pieces. See the description of the analysis option for
	  <a class="link" href="DecompilerOptions.html#AnalysisSplitArray">Splitting Array Accesses</a>.
	</p>
      </div>
      <div class="sect4">
<div class="titlepage"><div><div><h5 class="title">
<a name="TypeStructure"></a>Structure</h5></div></div></div>
	
	<p>
	  Structure data-types are fully supported. The Decompiler does not automatically infer structures
	  when analyzing a function; it propagates them into the function from explicitly
	  annotated sources, like input parameters or global variables.  Decompiler-directed creation of
	  structures can be triggered by the user (see <a class="xref" href="DecompilerWindow.html#ActionAutoStructure" title="Auto Create Structure">Auto Create Structure</a>).
	</p>
	<p>
	  For variables that are known to be structures, or pointers to structures, the Decompiler keeps
	  track of offsets into the variable and will render the name of the specific field being
	  accessed, using language specific access operators such as '.' or '-&gt;'. If the part of the
	  structure being accessed does not have a normal field name, either because the structure data-type
	  does not list a name at that position or because more than one field is being accessed
	  simultaneously, the Decompiler will either cast a pointer to a data-type of the correct size or
	  may automatically generate a token name representing the accessed portion.
          </p>
<div class="informalexample">
	    <pre class="programlisting">
	      struct1.a = 1;                // Assigning an integer to a field named "a"
	      fVar1 = ptr-&gt;b;               // Reading field "b" through a pointer
	      struct1._20_4_ = 0xff00ff00;  // Auto-generated name for assigning multiple fields at once
	    </pre>
          </div>
<p>
	  For an auto-generated token like <code class="code">_20_4_</code>, the first integer indicates the offset in bytes
	  of the access from the start of the structure, and the second integer indicates the number of bytes being accessed.
	</p>
	<p>
          If more than one field is being accessed simultaneously, the Decompiler may try to split
	  the access into logical pieces. See the description of the analysis option for
	  <a class="link" href="DecompilerOptions.html#AnalysisSplitStruct">Splitting Structure Accesses</a>.
	</p>
      </div>
      <div class="sect4">
<div class="titlepage"><div><div><h5 class="title">
<a name="TypeEnum"></a>Enumeration</h5></div></div></div>
	
	<p>
	  Enumerations are fully supported. The Decompiler can propagate enumerations from explicitly
	  annotated sources throughout a function onto constants, which are then displayed with the
	  appropriate label from the definition of the enumeration.  If the constant does not match a
	  single value in the enumeration definition, the Decompiler attempts to build a matching
	  value by <span class="emphasis"><em>or</em></span>-ing together multiple labels.  
	  The Decompiler can be made to break out constants representing packed <span class="emphasis"><em>flags</em></span>,
	  for instance, by labeling individual bit values within an enumeration.
	</p>
      </div>
      <div class="sect4">
<div class="titlepage"><div><div><h5 class="title">
<a name="TypeFunction"></a>Function Definition</h5></div></div></div>
	
	<p>
	  A <span class="bold"><strong>Function Definition</strong></span> in Ghidra is a data-type that encodes
	  information about the parameters and return value for a generic/unspecified function. 
	  A formal <span class="bold"><strong>function pointer</strong></span> is supported by the Decompiler as a pointer
	  data-type that points to a Function Definition. A Function Definition specifically encodes:
	  </p>
<div class="informalexample">
	    <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: bullet; ">
<li class="listitem" style="list-style-type: disc">
		The name and data-type of each parameter.
	      </li>
<li class="listitem" style="list-style-type: disc">
		Whether the function takes a variable number of parameters.
	      </li>
<li class="listitem" style="list-style-type: disc">
		The data-type associated with the return value.
	      </li>
<li class="listitem" style="list-style-type: disc">
		The name of a generic <span class="emphasis"><em>calling convention</em></span>
		associated with the function.
	      </li>
</ul></div>
	  </div>
<p>
	</p>
	<p>
	  The Function Definition itself does not encode any storage information.  Once the Function
	  Definition is associated with a Program, its generic calling convention maps to one of the
	  specific prototype models for the processor and compiler. The prototype model is then used
	  to assign storage for parameters and return values, wherever the Function Definition is applied.
	  A Function Definition is currently limited to a prototype model
	  with one of the following names:
	  </p>
<div class="informalexample">
	    <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: bullet; ">
<li class="listitem" style="list-style-type: disc">
		<span class="bold"><strong>__stdcall</strong></span>
	      </li>
<li class="listitem" style="list-style-type: disc">
		<span class="bold"><strong>__thiscall</strong></span>
	      </li>
<li class="listitem" style="list-style-type: disc">
		<span class="bold"><strong>__fastcall</strong></span>
	      </li>
<li class="listitem" style="list-style-type: disc">
		<span class="bold"><strong>__cdecl</strong></span>
	      </li>
<li class="listitem" style="list-style-type: disc">
		<span class="bold"><strong>__vectorcall</strong></span>
	      </li>
</ul></div>
	  </div>
<p>
	</p>
      </div>
      <div class="sect4">
<div class="titlepage"><div><div><h5 class="title">
<a name="TypeUnion"></a>Unions</h5></div></div></div>
	
	<p>
	  Unions data-types are fully supported.  The Decompiler does not automatically infer unions
	  when analyzing a function; it propagates them into the function from explicitly
	  annotated sources, like input parameters or global variables.
	</p>
	<p>
	  A union data-type, similarly to a structure, is made up of component data-types
	  called <span class="emphasis"><em>fields</em></span>.  But unlike a structure, a union's fields all share the same underlying
	  storage.  When the union is applied to a variable, each field potentially describes the whole variable.
	  At any given point where the variable is read or written, a different field may be in effect, even if the
	  underlying data hasn't changed.  The decompiler attempts to infer the particular field by following data-flow
	  to or from the point of use to determine which field best aligns with the specific operations being applied to the
	  variable.  The name of this recovered field is then printed in Decompiler output using syntax similar to that
	  used for structure fields.
	</p>
	<p>
	  Depending on the number and variety of fields within the union, it may not be possible
	  to fully distinguish which field is being used in a specific context. In this situation,
	  the Decompiler chooses the first field from the list of best matches.  The user has the
	  option of changing this choice with the <a class="xref" href="DecompilerWindow.html#ActionForceField" title="Force Field">Force Field</a> action.
	</p>
      </div>
      <div class="sect4">
<div class="titlepage"><div><div><h5 class="title">
<a name="TypeTypedef"></a>Typedefs</h5></div></div></div>
	
	<p>
	  Typedef data-types are fully supported.  The Decompiler does not automatically infer typedefs
	  when analyzing a function; it propagates them into the function from explicitly annotated sources.
	</p>
	<p>
	  A <span class="bold"><strong>typedef</strong></span> is copy of another data-type but with an alternate name.
	  In most cases it can be used interchangeably with the data-type it copies.
	  In general, the Decompiler treats a typedef as a distinct data-type, and it will maintain its identify
	  when it is assigned to variables and is propagated through data-flow.
	</p>
	<p>
	  Ghidra supports a specific set of attributes that can be placed directly on a typedef
	  that then distinguish it from the data-type it copies. This allows Ghidra to support some
	  non-standard data-types, although the typedef and its copy are no longer interchangeable.
	  The decompiler supports the following typedef properties:
	  </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: none; ">
<li class="listitem" style="list-style-type: none">Component Offset - See <a class="xref" href="DecompilerAnnotations.html#AttributeOffsetPointer" title="Offset Pointers">Offset Pointers</a>
</li>
<li class="listitem" style="list-style-type: none">Address Space - See <a class="xref" href="DecompilerAnnotations.html#AttributeAddressPointer" title="Address Space Pointers">Address Space Pointers</a>
</li>
</ul></div>
<p>
	</p>
      </div>
    </div>

    <div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="AnnotePointerAttributes"></a>Pointer Attributes</h4></div></div></div>
      
      <p>
	The Decompiler supports some specialized attributes that can be applied to pointer data-types, like offsets
	and address spaces (See below).  Ghidra implements these attributes on top of <span class="emphasis"><em>typedef</em></span> data-types only. In
	order to add attributes to pointers, a typedef of the underlying pointer data-type must be created first.
	Attributes can then be placed directly on the typedef from the Data Type Manager window
	(See <a class="ulink" href="help/topics/DataTypeManagerPlugin/data_type_manager_description.htm#Pointer_Typedef_Settings" target="_top">Pointer-Typedef Settings</a>).
      </p>
      <div class="sect4">
<div class="titlepage"><div><div><h5 class="title">
<a name="AttributeOffsetPointer"></a>Offset Pointers</h5></div></div></div>
	
	<p>
	  An <span class="bold"><strong>offset pointer</strong></span> points at a fixed offset relative to the start of its
	  underlying data-type. Typically the underlying data-type is a structure and the pointer points at a
	  specific field in the interior of the structure. But in general, the underlying data-type can be anything,
	  and the offset can point anywhere relative to that data-type, including either before or after.
	</p>
	<p>
	  An offset pointer is defined with all the same properties of a normal pointer.  It has an underlying
	  data-type and a size. On top of this an <span class="bold"><strong>offset</strong></span> is specified
	  as an integer attribute on the pointer (typedef). This is the number of bytes that need to be
	  added to the start of the underlying data-type to obtain the address actually being pointed at.
	</p>
	<p>
	  Because the <span class="emphasis"><em>underlying</em></span> data-type does not start directly at the address
	  contained in the offset pointer, one can also refer to the offset pointer's
	  <span class="bold"><strong>direct</strong></span> data-type, i.e. the data-type that <span class="emphasis"><em>is</em></span>
	  directly at the address contained in the pointer. If the pointer's offset is positive (and small),
	  the direct data-type will generally be that of a field of the <span class="emphasis"><em>underlying</em></span>
	  data-type.  If the offset is bigger than the size of the underlying data-type or is negative,
	  the direct data-type will be <span class="emphasis"><em>undefined</em></span>.
	</p>
	<p>
	  Offset pointers occur in code where the compiler has maintained knowledge of the position of
	  an underlying data-type relative to a pointer, even if the pointer no longer points directly at the data-type.
	  Because of this, the code may still access fields of the underlying data-type through the pointer.
	  Annotating a variable with an offset pointer allows the Decompiler to recover these accesses.
	</p>
	<p>
	  Within the Decompiler's output, the token <code class="code">ADJ</code> is used to indicate that the code is
	  accessing the underlying data-type through the offset pointer. The token uses functional syntax
	  to indicate the particular offset pointer. Then, once the <code class="code">ADJ</code> token is
	  applied, additional pointer syntax is used, i.e. <code class="code">-&gt;</code>, to indicate what part
	  of the underlying data-type is being accessed.
	  </p>
<div class="informalexample">
            <pre class="programlisting">
              ADJ(structoffptr)-&gt;field1 = 2;  // Accessing the underlying structure's field
              iVar1 = *ADJ(intoffptr);        // Accessing the underlying integer data-type
              ADJ(arrayoffptr)[4] = iVar2;    // Accessing the underlying array
            </pre>
	  </div>
<p>
	  If the offset pointer appears in Decompiler output without the <code class="code">ADJ</code> token being
	  applied, it is being treated as if it were a normal pointer to its direct
	  data-type.  This generally indicates the pointer is being used to access data outside the
	  underlying data-type. 
	</p>
      </div>
      <div class="sect4">
<div class="titlepage"><div><div><h5 class="title">
<a name="AttributeAddressPointer"></a>Address Space Pointers</h5></div></div></div>
	
	<p>
	  An <span class="bold"><strong>address space pointer</strong></span> is a normal pointer data-type with a specific
	  address space associated to it (See <a class="xref" href="DecompilerConcepts.html#ConceptAddressSpace" title="Address Space">Address Space</a>).  Its created by setting
	  the Address Space attribute on a typedef of a pointer. The attribute value is the name of the specific
	  address space.
	</p>
	<p>
	  Address space pointers are useful, when a program architecture supports more than one address space
	  containing addressable memory, such as separate <code class="code">code</code> and <code class="code">data</code> address spaces.
	  For a program and a specific section of its code that manipulates a pointer, it may not be easy to determine
	  which address space is being referred to. Address space pointers provide an additional annotation mechanism
	  to help the decompiler identify the correct address space for a pointer in context.
	</p>
	<p>
	  The Decompiler will automatically propagate an address space pointer data-type from parameters and
	  other annotated variables associated with a function. Any constant that the pointer reaches via propagation
	  is assumed to point into the address space associated with the pointer.  The correct symbol can then
	  be looked up, further informing the Decompiler output.
	</p>
      </div>
    </div>
 
    <div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="AnnoteForcing"></a>Forcing Data-types</h4></div></div></div>
      
      <p>
	The Decompiler performs <span class="bold"><strong>type propagation</strong></span> as part of its analysis
	on functions. Data-type information is collected from variable annotations and other sources,
	which is then propagated via data flow throughout the function to other variables and
	constants where the data-type may not be immediately apparent.  
      </p>
      <p>
	With few exceptions, a variable annotation is <span class="emphasis"><em>forcing</em></span> on the Decompiler in the sense
	that the storage location being annotated is considered an unalterable data-type source.  During
	type propagation, the data-type may propagate to other variables,
	but the variable representing the storage location being annotated is guaranteed to have
	the given name and that data-type; it will not be overridden.
      </p>
      <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="help/shared/warning.png"></td>
<th align="left"></th>
</tr>
<tr><td align="left" valign="top">
	Users should be aware that variable annotations are forcing on the Decompiler and may directly
	override aspects of its analysis.  Because of this, variable annotations are the most powerful way
	for the user to affect Decompiler output, but setting an incomplete or incorrect data-type as
	part of an annotation may produce poorer Decompiler output.
      </td></tr>
</table></div>
      <p>
	The major exception to forcing annotations is if the data-type in the annotation is <span class="emphasis"><em>undefined</em></span>.
	Ghidra reserves specific names to represent formally undefined data-types, such as:
	</p>
<div class="informalexample">
	  <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: bullet; ">
<li class="listitem" style="list-style-type: disc"><span class="bold"><strong>undefined1</strong></span></li>
<li class="listitem" style="list-style-type: disc"><span class="bold"><strong>undefined2</strong></span></li>
<li class="listitem" style="list-style-type: disc"><span class="bold"><strong>undefined4</strong></span></li>
<li class="listitem" style="list-style-type: disc"><span class="bold"><strong>undefined8</strong></span></li>
</ul></div>
	</div>
<p>
	These allow annotations to be made even when the user doesn't have information about a variable's data-type.
	The number in the name only specifies the number of bytes in the variable.
      </p>
      <p>
	The Decompiler views a variable annotation with an undefined data-type only as an indication of what name
	should be used if a variable at that storage address exists.  The data-type for the variable is filled in,
	using type propagation from other sources.
      </p>
      <p>
	For annotations that specifically label a function's formal parameters or return value, 
	the <a class="link" href="DecompilerAnnotations.html#PrototypeSignatureSource" title="Signature Source">Signature Source</a> also affects how they're treated by the Decompiler.
	If the Signature Source is set to anything other than <span class="emphasis"><em>DEFAULT</em></span>, there is a forced
	one-to-one correspondence between variable annotations and actual parameters in the Decompiler's
	view of the function.  This is stronger than just forcing the data-type; the existence or nonexistence of
	the variable itself is forced by the annotation in this case.  If the Signature Source is forcing and
	there are no parameter annotations, a <span class="emphasis"><em>void</em></span> prototype is forced on the function.
      </p>
      <p>
	A forcing Signature Source is set typically if debug symbols for the function are read in during
	Program import (<span class="emphasis"><em>IMPORTED</em></span>) or if the user manually edits the function prototype
	directly (<span class="emphasis"><em>USER_DEFINED</em></span>).
      </p>
      <p>
	If an annotation and the Signature Source force a parameter to exist, specifying an
	<span class="emphasis"><em>undefined</em></span> data-type in the annotation still directs the Decompiler to fill in
	the variable's data-type using type propagation.  The same holds true for the return value; an
	<span class="emphasis"><em>undefined</em></span> annotation fixes the size of the return value, but the Decompiler
	fills in its own data-type.
      </p>
      <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="help/shared/note.png"></td>
<th align="left"></th>
</tr>
<tr><td align="left" valign="top">
	The Decompiler may still use an <span class="emphasis"><em>undefined</em></span> data-type to label a variable,
	even after type propagation.  If a variable is simply copied around within a function and there
	are no other substantive operations or annotations on the variable, the Decompiler may decide the undefined
	data-type is appropriate.
      </td></tr>
</table></div>
    </div>
    
  </div>

  <div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="AnnoteStorage"></a>Variable Storage</h3></div></div></div>
    
    <p>
      Every variable annotation is associated with a single <span class="emphasis"><em>storage location</em></span>, where the
      value of the variable is stored during execution: generally a register, stack location, or an address
      in the load image of the Program.  The storage location does not necessarily hold the value for that
      variable at all points of execution, and it is possible for the variable value to be held in
      <span class="emphasis"><em>different</em></span> storage locations at different points of execution.  The set of execution
      points where the storage location <span class="emphasis"><em>does</em></span> hold the variable value is called the annotation
      <span class="bold"><strong>scope</strong></span>; this is distinct from, but influenced by, the scope of the
      variable itself. The different types of storage location are listed below.
    </p>
    <div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="VariableStorageImage"></a>Load-image Address</h4></div></div></div>
      
      <p>
	A <span class="bold"><strong>load-image address</strong></span> is a concrete address in the load image of the Program,
	typically in the <span class="bold"><strong>ram</strong></span> address space. This kind of
	storage must be backed by a formal memory block for the Program, which typically corresponds to a specific
	program section, such as the <code class="code">.text</code> or <code class="code">.bss</code> section.  Because it is in the
	load image directly, an annotation with this storage shows up directly in any Listing
	window and can be directly manipulated there. In much of the Ghidra documentation, these annotations
	are referred to as <span class="bold"><strong>Data</strong></span>. See the
	<a class="ulink" href="help/topics/DataPlugin/Data.htm" target="_top">Data</a> section, in particular.
      </p>
      <p>
	Although specific architectures may vary, a storage location at a load image address generally
	represents a formal <span class="emphasis"><em>global</em></span> variable, and the annotation is in scope
	across all Program execution. For the Decompiler, the storage location is treated as a
	a single <span class="emphasis"><em>persistent</em></span> variable in all functions that reference it. Within a
	function, all distinct references (varnodes) to the storage location are merged. The Decompiler
	expects a value at the storage location to exist from <span class="emphasis"><em>before</em></span> the start of
	the function, and any change to the value must be explicitly represented as an assignment to
	the variable in Decompiler output.
      </p>
    </div>
    <div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="VariableStorageStack"></a>Stack Address</h4></div></div></div>
      
      <p>
	A <span class="bold"><strong>stack address</strong></span> is an address in the <span class="emphasis"><em>stack frame</em></span>
	of a particular function in the Program.  Formally, a stack address is defined as an offset relative to the
	incoming value of the <span class="emphasis"><em>stack pointer</em></span> and exists in the
	<span class="bold"><strong>stack</strong></span> address space associated with the function. See the discussion
	in <a class="xref" href="DecompilerConcepts.html#ConceptAddressSpace" title="Address Space">Address Space</a>. A <span class="bold"><strong>stack annotation</strong></span> then is a variable annotation
	with a stack address as its storage location. It exists only in the scope of a
	single function and the variable must be <span class="emphasis"><em>local</em></span> to that function. 
      </p>
      <p>
	Within a <span class="emphasis"><em>Listing</em></span> window, a stack annotation is displayed as part of the function header
	at the entry point address of the function, with a syntax similar to:
	</p>
<div class="informalexample">
	  <code class="code">undefined4 Stack[-0x14]:4 local_14</code>
	</div>
<p>
	The middle field (the <span class="emphasis"><em>Variable Location</em></span> field) indicates that the storage location is on the
	stack, and the value in brackets indicates the offset of the storage location relative to the incoming
	stack pointer. The value after the colon indicates the number of bytes in the storage location.
      </p>
      <p>
	Currently, the entire body of the function is included
	in the scope of any stack annotation, and the Decompiler will allow only a single variable to exist
	at the stack address. A stack annotation can be a formal parameter to the function, but otherwise the
	Decompiler does not expect to see a value that exists before the start of the function.
      </p>
      <p>
	The Decompiler will continue to perform <span class="emphasis"><em>copy propagation</em></span> and other transforms on
	stack locations associated with a variable annotation. In particular, within Decompiler output,
	if the value is simply copied to another location,
	a specific write operation to a stack address may not show up as an explicit assignment to its variable.
      </p>
    </div>
    <div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="VariableStorageRegister"></a>Register</h4></div></div></div>
      
      <p>
	A variable annotation can refer to a specific <span class="emphasis"><em>register</em></span> for the processor associated
	with the Program. In general, such an annotation will be for a variable local to a particular function.
	Within a <span class="emphasis"><em>Listing</em></span> window, this annotation is displayed as part of the function header, with
	syntax like:
	</p>
<div class="informalexample">
	  <code class="code">int EAX:4 iVar1</code>
	</div>
<p>
	The <span class="emphasis"><em>Variable Location</em></span> field displays the name of the particular register attached to
	the annotation, and the value after the colon indicates the number of bytes in the register.
      </p>
      <p>
	For local variable annotations with a register storage location, there is an expectation that the
	register may be reused for different variables at different points of execution within the function.
	There may be more than one annotation, for different variables, that share the same register
	storage location.
	An annotation is associated with a <span class="emphasis"><em>first use point</em></span> that describes where
	the register first holds a value for the particular variable (see the discussion - <a class="xref" href="DecompilerConcepts.html#ConceptVarnodeSSA" title="Varnodes in the Decompiler">Varnodes in the Decompiler</a>).
	The entire scope of the annotation is limited to the address regions between the first use point
	and any points where the value is read. The Decompiler may extend the scope as part of its
	<span class="emphasis"><em>merging</em></span> process, but the full extent is not stored in the annotation.
      </p>
    </div>
    <div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="VariableStorageTemp"></a>Temporary Register</h4></div></div></div>
      
      <p>
	Variable annotations can have a <span class="emphasis"><em>temporary register</em></span> as a storage location.
	A temporary register is not specific to a processor but is produced at various stages of
	the decompilation process. See the discussion of the <span class="bold"><strong>unique</strong></span>
	space in <a class="xref" href="DecompilerConcepts.html#ConceptAddressSpace" title="Address Space">Address Space</a>. These registers do not have a meaningful name, and
	the specific storage address may change on successive decompilations. So, within a
	<span class="emphasis"><em>Listing</em></span> window, this annotation is displayed as part of the function header
	with syntax like:
	</p>
<div class="informalexample">
	  <code class="code">int HASH:5f96367122:4 iVar2</code>
	</div>
<p>
	The <span class="emphasis"><em>Variable Location</em></span> field displays the internal hash used to uniquely
	identify the temporary register within the data flow of the function.
      </p>
      <p>
	A temporary register annotation must be for a local variable, and as with an ordinary register,
	the annotation is associated with a <span class="emphasis"><em>first use point</em></span> that describes
	where the temporary register first holds a value for the variable.
      </p>
    </div>
  </div>
</div>

<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="AnnotePrototype"></a>Function Prototypes</h2></div></div></div>
  
  <p>
    Every formal Function in Ghidra is associated with a set of variable annotations and other properties that
    make up the <span class="bold"><strong>function prototype</strong></span>. Due to the nature of reverse engineering,
    the function prototype may include only partial information and may be built up over time. Individual
    elements include:
    </p>
<div class="informalexample">
    <div class="variablelist"><dl class="variablelist">
<dt><span class="term"><span class="bold"><strong>Input Parameters</strong></span></span></dt>
<dd>
	<p>
	  Each formal input to the function can have a Variable Annotation that describes its name, data-type,
	  and storage location. The storage location applies at the moment control flow enters the function.
	  If annotations exist, they are shown
	  in a Listing window as part of the Function header, and they usually correspond directly with symbols in the
	  <span class="emphasis"><em>function declaration</em></span> produced by the Decompiler.
	</p>
      </dd>
<dt><span class="term"><span class="bold"><strong>Return Value</strong></span></span></dt>
<dd>
	<p>
	  The value returned by a function can have a special Variable Annotation that describes its data-type
	  and storage location. The storage location applies at the moment control flow exits the function. If it exists, the annotation is shown
	  in a Listing window as part of the Function header with the name <code class="code">&lt;RETURN&gt;</code>, and it usually
	  corresponds directly with the return value in the <span class="emphasis"><em>function declaration</em></span> produced by
	  the Decompiler.
	</p>
      </dd>
<dt><span class="term"><span class="bold"><strong>Auto-Parameters</strong></span></span></dt>
<dd>
	<p>
	  Specific prototypes may require auto-parameters like <span class="bold"><strong>this</strong></span>
	  or <span class="bold"><strong>__return_storage_ptr__</strong></span>.  These are special input parameters
	  that compilers may use to implement specific high-level language concepts. See the discussion
	  in <a class="xref" href="DecompilerConcepts.html#ConceptAutoParameters" title="Auto-Parameters">Auto-Parameters</a>. Within Ghidra, auto-parameters are automatically created by the
	  <a class="ulink" href="help/topics/FunctionPlugin/Variables.htm#Edit_Function" target="_top">Function Editor Dialog</a>
	  if the desired prototype requires them.
	  Within a Listing window, auto-parameters look like other parameter annotations, but the storage field shows the
	  string <code class="code">(auto)</code>.  Decompiler output will generally display auto-parameters as explicit variables
	  rather than hiding them.
	</p>
      </dd>
<dt><span class="term"><span class="bold"><strong>Calling Convention</strong></span></span></dt>
<dd>
	<p>
	  The calling convention used by the function is specified as part of the function prototype. The convention
	  is specified by name, referring to the formal <a class="xref" href="DecompilerConcepts.html#ConceptPrototypeModel" title="Prototype Model">Prototype Model</a> that describes how storage
	  locations are selected for individual parameters along with other information about how the compiler treats
	  the function. Available models are determined by the processor and compiler, but may be extended by the user
	  (see <a class="xref" href="DecompilerOptions.html#ExtensionOptions" title="Specification Extensions">Specification Extensions</a>).
	</p>
	<p>
	  In the absence of input parameter and return value annotations, the Decompiler will use the prototype model as
	  part of its analysis to <span class="emphasis"><em>discover</em></span> the input parameters and the return value of the function.
	</p>
	<p>
	  The name <span class="bold"><strong>unknown</strong></span> is reserved to indicate that nothing is known about the calling convention.  If
	  set to <span class="bold"><strong>unknown</strong></span>, depending on context, the Decompiler may assign the calling convention based on
	  the <span class="emphasis"><em>Prototype Evaluation</em></span> option (see <a class="xref" href="DecompilerOptions.html#OptionProtoEval"><span class="bold"><strong>Prototype Evaluation</strong></span></a>), or it
	  may use the default calling convention for the architecture.
	</p>
      </dd>
<dt><span class="term"><span class="bold"><strong>Variable Arguments</strong></span></span></dt>
<dd>
	<p>
	  Functions have a boolean property called <span class="bold"><strong>variable arguments</strong></span>, which can be turned on
	  if the function is capable of being passed a variable number of inputs.  This property informs the Decompiler that
	  the function may take additional parameters beyond any with an explicit variable annotation.
	  This affects decompilation of any function which calls the <span class="emphasis"><em>variable arguments</em></span> function, allowing
	  the Decompiler to discover unlisted parameters at a given call site.
	</p>
      </dd>
<dt><span class="term"><span class="bold"><strong>No Return</strong></span></span></dt>
<dd>
	<p>
	  A function can be marked with the <span class="bold"><strong>no return</strong></span> property, meaning that once
	  a call is made to the function, execution will never return to the caller. The Decompiler uses this to
	  compute the correct control flow in any calling functions.
	</p>
      </dd>
<dt><span class="term"><span class="bold"><strong>In-Line</strong></span></span></dt>
<dd>
	<p>
	  If the <span class="bold"><strong>in-line</strong></span> property is turned on for a particular function,
	  it directs the Decompiler to inline the effects of the function into the decompilation of any of its calling functions.
	  The function will no longer appear as a direct function call in the decompilation, but all of its data flow
	  will be incorporated into the calling function.
	</p>
	<p>
	  This is useful for <span class="emphasis"><em>bookkeeping</em></span> functions, where it is important for the Decompiler to
	  <span class="emphasis"><em>see</em></span> its effects on the calling function.  Functions that set up the stack frame for a caller or
	  functions that look up or dispatch a switch destination are typical examples that should be marked <span class="emphasis"><em>in-line</em></span>.
	</p>
      </dd>
<dt><span class="term"><span class="bold"><strong>Call-fixup</strong></span></span></dt>
<dd>
	<p>
	  This property is similar in spirit to marking a function as <span class="emphasis"><em>in-line</em></span>.
	  A <span class="bold"><strong>call-fixup</strong></span> directs the Decompiler to replace any call to the function with a specific
	  chunk of raw p-code.  The decompilation of any calling function no longer shows the function call, but the chunk
	  of p-code incorporates the called function's effects.
	</p>
	<p>
	  Call-fixups are more flexible than just inlining a function.  The call-fixup chunk can be tailored to incorporate all of,
	  just a part of, or something different to the behavior of the function.
	</p>
	<p>
	  Call-fixups are specified by name.  The name and associated p-code chunk are typically defined in the
	  <span class="emphasis"><em>compiler specification</em></span> for the Program. Users can extend the available set
	  of call-fixups (see <a class="xref" href="DecompilerOptions.html#ExtensionOptions" title="Specification Extensions">Specification Extensions</a>).
	</p>
      </dd>
</dl></div>
    </div>
<p>
  </p>
  <div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="PrototypeSignatureSource"></a>Signature Source</h3></div></div></div>
    
    <p>
      Ghidra records a <span class="bold"><strong>Signature Source</strong></span> for every function,
      indicating the origin of its prototype information.  This is
      similar to the <span class="emphasis"><em>Symbol Source</em></span> attached to Ghidra's symbol annotations
      (see the documentation for
      <a class="ulink" href="help/topics/SymbolTablePlugin/symbol_table.htm#Set_Filter" target="_top">Filtering</a>
      in the Symbol Table).  The possible types are:
      </p>
<div class="informalexample">
	<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: none; ">
<li class="listitem" style="list-style-type: none">
<span class="emphasis"><em>DEFAULT</em></span> - for basic or no information</li>
<li class="listitem" style="list-style-type: none">
<span class="emphasis"><em>ANALYSIS</em></span> - for information derived by an Analyzer</li>
<li class="listitem" style="list-style-type: none">
<span class="emphasis"><em>IMPORTED</em></span> - for information imported from an external source</li>
<li class="listitem" style="list-style-type: none">
<span class="emphasis"><em>USER_DEFINED</em></span> - for information set by the user</li>
</ul></div>
      </div>
<p>
    </p>
    <p>
      Upon import of the Program, if there are debugging symbols available, Ghidra will build
      annotations of the function's parameters and set the Symbol Source type to <span class="emphasis"><em>IMPORTED</em></span>.
      Otherwise, it will generally be set to <span class="emphasis"><em>DEFAULT</em></span>.
    </p>
    <p>
      However, Ghidra adjusts the Signature Source for a function if there is any change to the
      prototype.  In particular, if the user adds, removes, or edits variable annotations
      for the function's parameters or return value, Ghidra automatically converts the Signature
      Source to be <span class="emphasis"><em>USER_DEFINED</em></span>.
    </p>
    <p>
      If the Signature Source is set to anything other than <span class="emphasis"><em>DEFAULT</em></span>, the
      function's prototype information is forcing on the Decompiler (see the discussion
      in <a class="xref" href="DecompilerAnnotations.html#AnnoteForcing" title="Forcing Data-types">Forcing Data-types</a>).
    </p>
  </div>
  <div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="PrototypeDiscover"></a>Discovering Parameters</h3></div></div></div>
    
    <p>
      The input parameter and return value annotations of the function prototype, like
      any variable annotations, can be forcing on the Decompiler
      (see the complete discussion in <a class="xref" href="DecompilerAnnotations.html#AnnoteForcing" title="Forcing Data-types">Forcing Data-types</a>).
      But keep in mind:
    </p>
    <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="help/shared/warning.png"></td>
<th align="left"></th>
</tr>
<tr><td align="left" valign="top">
      The input parameters and return value are all forced on the Decompiler as a unit based on the
      <span class="emphasis"><em>Signature Source</em></span>. They are all forced if the type is set to anything
      other than <span class="emphasis"><em>DEFAULT</em></span>; otherwise none of them are forced.
    </td></tr>
</table></div>
    <p>
      If the function prototype's annotations are not forcing, the Decompiler will attempt to discover the parameters
      and return value using the calling convention.  The prototype model underlying the calling convention
      dictates which storage locations can be considered as parameters and their formal ordering.
    </p>
  </div>
  <div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="PrototypeCustom"></a>Custom Storage</h3></div></div></div>
    
    <p>
      If there are parameter or return value annotations that do not agree with the calling convention that
      has been set, the function prototype is said to be using <span class="bold"><strong>custom storage</strong></span>.
      Using the <a class="ulink" href="help/topics/FunctionPlugin/Variables.htm#Edit_Function" target="_top">Function Editor Dialog</a>
      for instance, any storage location can be specified as a parameter, and a completely custom prototype
      can be built for the function.
    </p>
    <p>
      The Decompiler will disregard the calling convention's rules in this situation and use the custom storage
      locations for parameters and the return value.  Other aspects of the calling convention, like the
      <span class="emphasis"><em>unaffected</em></span> list, will still be used.
    </p>
  </div>
</div>

<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="AnnoteMutability"></a>Data Mutability</h2></div></div></div>
  
  <p>
    <span class="bold"><strong>Mutability</strong></span> is a description of how values in a specific memory region,
    either a single variable or a larger block, can change during Program execution based either on
    properties or established rules.  Ghidra recognizes the mutability settings:
    </p>
<div class="informalexample">
    <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: bullet; ">
<li class="listitem" style="list-style-type: disc">Normal</li>
<li class="listitem" style="list-style-type: disc">Constant - (read-only)</li>
<li class="listitem" style="list-style-type: disc">Volatile</li>
</ul></div>	
    </div>
<p>
    Mutability affects Decompiler analysis and can have a large impact on the output.
  </p>
  <p>
    Most memory has <span class="bold"><strong>normal</strong></span> mutability;
    the value at the memory location may change over the course of executing the Program, but for a given
    section of code, the value will not change unless an instruction explicitly writes to it.
  </p>
  <p>
    Mutability can be set on an entire block of memory in the Program, typically from the
    <a class="ulink" href="help/topics/MemoryMapPlugin/Memory_Map.htm#View_Memory_Map" target="_top">Memory Map</a>.
    It can also be set as part of a single Variable Annotation.  From a Listing window, for instance,
    use the <a class="ulink" href="help/topics/DataPlugin/Data.htm#Data_Settings" target="_top">Settings</a> dialog.
  </p>
  <div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="MutabilityReadOnly"></a>Read-only</h3></div></div></div>
    
    <p>
      The <span class="bold"><strong>constant</strong></span> mutability setting indicates that values within
      the memory region are read-only and don't change during Program execution.  If a read-only variable is
      accessed in a function being analyzed by the Decompiler, its constant value, if present in the
      Program's <span class="emphasis"><em>load image</em></span>, replaces the variable within data flow for the
      function.  The Decompiler may propagate the constant and fold it in to other operations, which
      can have a substantial impact on the final output.
    </p>
  </div>
  <div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="MutabilityVolatile"></a>Volatile</h3></div></div></div>
    
    <p>
      The <span class="bold"><strong>volatile</strong></span> mutability setting indicates that values within
      the memory region may change unexpectedly, even if the code currently executing does not directly
      write to it.  Accessing a variable within a volatile region, either reading or writing, can have other
      side-effects on the machine state, and it cannot in general be treated as normal variable.
      If a volatile variable is accessed in a function being analyzed by the Decompiler,
      each access is expressed as a copy statement on its own line, separated from other expressions,
      so that the its position within the code and any sequence of accesses is clearly indicated.
      Any access, either read or write, will always be displayed, even if the value is not directly
      used by the function. The token representing the variable will be displayed using the
      <span class="bold"><strong>Special</strong></span> color, highlighting that the access is volatile
      (See <a class="xref" href="DecompilerOptions.html#DisplayTokenColor"><span class="bold"><strong>Color for &lt;token&gt;</strong></span></a>).
      </p>
<div class="informalexample">
	<pre class="programlisting">
	  X = <span class="redtext">SREG</span>;              // Reading volatile SREG
	  <span class="redtext">DAT_mem_002b</span> = 0x20;   // Writing volatile DAT
	</pre>
      </div>
<p>
    </p>
  </div>
</div>

<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="AnnoteConstants"></a>Constant Annotations</h2></div></div></div>
  
  <p>
    Ghidra provides numerous actions to control how a specific constant is formatted or displayed.
    An annotation can be applied directly to a constant in a Decompiler window, which always affects
    Decompiler output. Or, an annotation can be applied to the constant operand of a specific machine
    instruction displayed in a Listing window.  In this case, to the extent possible, the Decompiler
    attempts to track the operand and apply the annotation to the matching constant in the Decompiler output.
    However, the constant may be transformed from its value in the original machine instruction during the Decompiler's
    analysis.  The Decompiler will follow the constant through one of the following simple transformations, but
    otherwise the annotation will not be applied.
    </p>
<div class="informalexample">
    <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: bullet; ">
<li class="listitem" style="list-style-type: disc">Signed or zero extension</li>
<li class="listitem" style="list-style-type: disc">Bitwise negation</li>
<li class="listitem" style="list-style-type: disc">Integer negation - Two's complement</li>
<li class="listitem" style="list-style-type: disc">Add or subtract 1</li>
</ul></div>
    </div>
<p>
  </p>
  <div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="ConstantEquates"></a>Equates</h3></div></div></div>
    
    <p>
      Ghidra can create an association between a name and a constant, called an <span class="bold"><strong>equate</strong></span>.
      An equate is a descriptive string that is intended to replace the numeric form of the constant, and equates
      across the entire Program can be viewed from the
      <a class="ulink" href="help/topics/EquatePlugin/Equates.htm#Equate_Table" target="_top">Equates Table</a>.
    </p>
    <p>
      An equate can be applied to a machine instruction with a constant
      operand by using the <a class="ulink" href="help/topics/EquatePlugin/Equates.htm#Set_Equate" target="_top">Set Equate</a>
      menu from a Listing window. If the Decompiler successfully follows the operand to a matching constant,
      the equate's name is displayed as part of the Decompiler's output as well as in any Listing window.
      A transformed operand is displayed as an expression, where the transforming operation is applied to
      the equate symbol representing the original constant.
    </p>
    <p>
      Alternatively, an equate can be applied directly to a constant from a Decompiler window using its
      <a class="xref" href="DecompilerWindow.html#ActionSetEquate" title="Set Equate...">Set Equate...</a> menu.  The constant may or may not have a corresponding instruction
      operand but will be displayed in Decompiler output using the descriptive string.
    </p>
  </div>
  <div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="ConstantConversions"></a>Format Conversions</h3></div></div></div>
    
    <p>
      Ghidra can apply a <span class="bold"><strong>format conversion</strong></span> to any integer constant that is displayed
      in Decompiler output.
    </p>
    <p>
      A conversion can be applied to the machine instruction containing the constant
      as an operand using the <a class="ulink" href="help/topics/EquatePlugin/Equates.htm#Convert" target="_top">Convert</a> menu option
      from a Listing window. If the Decompiler successfully traces the operand to a matching constant,
      the format conversion is applied in the Decompiler output as well as in the Listing window.
    </p>
    <p>
      Alternately, a conversion can be applied directly to an integer constant in a
      Decompiler window using its <a class="xref" href="DecompilerWindow.html#ActionConvert" title="Convert">Convert</a> menu option. The constant may or may not
      have a corresponding instruction operand but is displayed in Decompiler output using the conversion.
    </p>
    <p>
      Conversions applied by the Decompiler are currently limited to:
      </p>
<div class="informalexample">
      <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: bullet; ">
<li class="listitem" style="list-style-type: disc">Binary - 0b01100001</li>
<li class="listitem" style="list-style-type: disc">Decimal - 97</li>
<li class="listitem" style="list-style-type: disc">Hexadecimal - 0x61</li>
<li class="listitem" style="list-style-type: disc">Octal - 0141</li>
<li class="listitem" style="list-style-type: disc">Char - 'a'</li>
</ul></div>
      </div>
<p>
      If necessary, a header matching the format is prepended to the representation string, either "0b", "0x" or just
      "0".  A conversion will not switch the signedness of the constant; the signed or unsigned data-type associated
      with the constant, as determined by analysis, is preserved.  If the constant is negative, with a signed data-type,
      the representation string will always start with a '-' character.
    </p>
  </div>
</div>

<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="AnnoteRegister"></a>Register Values</h2></div></div></div>
  
  <p>
    A <span class="bold"><strong>register value</strong></span> in this context is a region of code in the Program
    where a specific register holds a known constant value.  Ghidra maintains an explicit list of these values for
    the Program (see the documentation for <a class="ulink" href="help/topics/RegisterPlugin/Registers.htm" target="_top">Register Values</a>),
    which the Decompiler can use when analyzing a function.
    A register value benefits Decompiler analysis, especially if the original compiler was aware
    of the constant value, as the Decompiler can recover address references calculated as offsets relative to the register
    and otherwise propagate the constant.
  </p>
  <p>
    A <span class="emphasis"><em>register value</em></span> is set by highlighting the region of code in a Listing window and then invoking the
    <a class="ulink" href="help/topics/RegisterPlugin/Registers.htm#SetRegisterValues" target="_top">Set Register Values...</a> command
    from the pop-up menu.  The beginning and end of a region is indicated in a Listing window with
    <code class="code">assume</code> directives, and regions can be generally viewed from the
    <a class="ulink" href="help/topics/RegisterPlugin/Registers.htm#Register_Manager" target="_top">Register Manager</a> window.
  </p>
  <p>
    In order for a particular register value to affect decompilation, the region of code associated with the
    value must contain the entry point of the function, and of course the function must read from the register.
    Only the initial reads of the register are replaced with the constant value.
    The Decompiler will continue to respect later instructions that write to the register, even if the
    instruction is inside the register value's region.
    If a register value's region starts in the middle of a function, decompilation is <span class="emphasis"><em>not</em></span>
    affected at all.
  </p>
  <div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="AnnoteContextRegister"></a>Context Registers</h3></div></div></div>
    
    <p>
      There is a special class of registers called <span class="bold"><strong>context registers</strong></span> whose
      values have a different affect on analysis and decompilation than described above.
    </p>
    <div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="help/shared/tip.png"></td>
<th align="left"></th>
</tr>
<tr><td align="left" valign="top">
      <span class="emphasis"><em>Context registers</em></span> are inputs to the disassembly decoding process and directly affect which
      machine instructions are created.
    </td></tr>
</table></div>
    <p>
      The value in a context register is examined when Ghidra decodes machine instructions from the underlying
      bytes in the Program. A specific value generally corresponds to a specific <span class="emphasis"><em>execution mode</em></span>
      of the processor. The ARM processor <span class="emphasis"><em>T bit</em></span>, for instance, which selects whether the
      processor is executing ARM or THUMB instructions, is modeled as a context register in Ghidra.
      The same set of bytes in the Program can be decoded to machine instructions in more than one way,
      depending on context register values.
    </p>
    <p>
      Bytes are typically decoded once using context register values
      established at the time of disassembly. From Ghidra's more static view of execution, a context register holds
      only a single value at any point in the code, but the same context register can hold different values for
      different regions of code. Setting a new value on a region of the Program will affect any subsequent disassembly
      of code within that region.  
    </p>
    <p>
      If a context register value is changed for a region that has already been disassembled, in order to see
      the affect of the change, the machine instructions in the region need to be cleared, and disassembly needs
      to be triggered again (see the documentation on the
      <a class="ulink" href="help/topics/ClearPlugin/Clear.htm#Clear_Code_Bytes" target="_top">Clear Plugin</a>).
    </p>
    <p>
      Values for a context register are set in the same way as for any other register, using the
      <a class="ulink" href="help/topics/RegisterPlugin/Registers.htm#SetRegisterValues" target="_top">Set Register Values...</a> command
      described above.  Within the
      <a class="ulink" href="help/topics/RegisterPlugin/Registers.htm#Register_Manager" target="_top">Register Manager</a> window,
      context registers are generally grouped together under the <span class="emphasis"><em>contextreg</em></span> pseudo-register heading.
      For details about how context registers are used in processor modeling, see
      the document "SLEIGH: A Language for Rapid Processor Specification."
    </p>
    <p>
      Because context registers affect machine instructions, they also affect the underlying p-code and
      have a substantial impact on decompilation.  Although details vary by processor, context register
      values are typically established during the initial import and analysis of a Program and aren't changed
      frequently.
    </p>
  </div>
</div>

</div></body>
</html>
